hysop.operator.base.spectral_operator module

class hysop.operator.base.spectral_operator.PlannedSpectralTransform(transform_group, tag, symbolic_transform, action, custom_input_buffer=None, custom_output_buffer=None, matching_forward_transform=None, dump_energy=None, plot_energy=None, compute_energy_frequencies=None, **kwds)

Bases: object

A planned spectral transform is an AppliedSpectralTransform wrapper. This object will be handled by the transform planner.

DEBUG = False

property backend

compute_energy(simulation, wait_for)

configure_input_buffer(buf)

configure_output_buffer(buf)

determine_buffer_shape(transform_shape, target_is_buffer, offsets, axes)

property dfield

discretize(**kwds)

property discretized

property field

property full_input_buffer

property full_output_buffer

get_mapped_full_input_buffer()

get_mapped_full_output_buffer()

get_mapped_input_buffer()

get_mapped_output_buffer()

get_mem_requests(**kwds)

initialize(**kwds)

property initialized

property input_axes

property input_buffer

property input_dtype

property input_shape

property input_slices

input_symbolic_array(name, **kwds)

Create a symbolic array that will be bound to input transform array.

property input_transform_shape

property is_backward

property is_forward

property name

property op

property output_axes

property output_buffer

property output_dtype

property output_parameters

property output_shape

property output_slices

output_symbolic_array(name, **kwds)

Create a symbolic array that will be bound to output transform array.

property output_transform_shape

plot_energy(simulation, wait_for)

property ready

property s

setup(work)

property symbol

property tag

property transform_group

property transforms

class hysop.operator.base.spectral_operator.SpectralComputationalGraphNodeFrontend(implementation, enforce_implementation=True, **kwds)

Bases: ComputationalGraphNodeFrontend

Initialize a ComputationalGraphNodeFrontend

Parameters:

• implementation (Implementation, optional, defaults to None) – target implementation, should be contained in available_implementations(). If None, implementation will be set to default_implementation().

• base_kwds (dict, optional, defaults to None) – Base class keywords arguments. If None, an empty dict will be passed.

• impl_kwds – Keywords arguments that will be passed towards implementation implemention __init__.

implementation

the implementation key

Type:

Implementation

backend

the backend corresponding to implementation

Type:

Backend

impl

the implementation class

Type:

ComputationalGraphNodeGenerator or ComputationalGraphNode

impl_kwds

Keywords arguments that will be passed towards implementation implemention impl.__init__ during a call to _generate.

classmethod get_actual_implementation(implementation, enforce_implementation=True, cl_env=None, **kwds)

Parameters:

• implementation (Implementation, optional, defaults to None) – User desired target implementation.

• enforce_implementation (bool, optional, defaults to True) –

  If this is set to True, input implementation is enforced. Else, this function may select another implementation when some conditions are met:

  Case 1: Host FFT by mapping CPU OpenCL buffers

  Conditions:

  a/ input implementation is set to OPENCL b/ cl_env.device is of type CPU c/ Implementation.PYTHON is a valid operator implementation d/ Target python operator supports OPENCL as backend e/ OpenCL platform has zero copy capabilities (cannot be checked)

  => If cl_env is not given, this will yield a RuntimeError => In this case PYTHON implementation is chosen instead.

  Buffer are mapped to host. By default this should give multithread FFTW + multithreaded numba.

  For all other cases, this parameter is ignored.

Notes

clFFT (gpyFFT) support for OpenCL CPU devices is a bit neglected. This function allows to override the implementation target from OPENCL to PYTHON when a CPU OpenCL environment is given as input.

By default, the CPU FFT target is FFTW (pyFFTW) which has much better support (multithreaded fftw + multithreaded numba).

OpenCL buffers are mapped to host memory with enqueue_map_buffer (this makes the assumption thal all OpenCL buffers have been allocated with zero-copy capability in the target OpenCL platform).

class hysop.operator.base.spectral_operator.SpectralOperatorBase(fft_interface=None, fft_interface_kwds=None, **kwds)

Bases: object

Common implementation interface for spectral based operators.

Initialize a spectral operator base. kwds: dict

Base class keyword arguments.

property FFTI

property backend

discretize(**kwds)

get_field_requirements()

get_mem_requests(**kwds)

get_node_requirements()

get_work_properties(**kwds)

initialize(**kwds)

min_fft_alignment = 32

new_transform_group(tag=None, mem_tag=None)

Register a new SpectralTransformGroup to this spectral operator. A SpectralTransformGroup is an object that collect forward and backward field transforms as well as symbolic expressions and wave_numbers symbols.

pre_initialize(**kwds)

setup(work)

class hysop.operator.base.spectral_operator.SpectralTransformGroup(op, tag, mem_tag, **kwds)

Bases: object

Build and check a FFT transform group.

This object tells the planner to build a full forward transform for all given forward_fields. The planner will also build backward transforms for all specified backward_fields.

The object will also automatically build per-axis wavenumbers up to certain powers, extracted from user provided sympy expressions.

Finally boundary condition (ie. transform type) compability will be checked by using user provided sympy expressions.

Calling a forward transform ensures that forward source field is read-only and not destroyed.

Parameters:

• op (SpectralOperatorBase) – Operator that creates this SpectralTransformGroup.

• tag (str) – A tag to identify this transform group. Each tag can only be registered once in a SpectralOperatorBase instance.

• Attributes

• -----------

• tag – SpectralTransformGroup identifier.

• mem_tag (str) – SpectralTransformGroup memory pool identifier.

• forward_transforms (list of forward SpectralTransform) – Forward fields to be planned for transform, according to Field boundary conditions.

• backward_fields (list of backward SpectralTransform) – Backward fields to be planned for transform, according to Field boundary conditions.

Notes

All forward_fields and backward_fields have to live on the same domain and their boundary conditions should comply with given expressions.

DEBUG = False

property backward_fields

property backward_transforms

classmethod build_wave_number(domain, grid_resolution, backend, wave_number, compute_dtype, compute_axes, compute_resolution)

classmethod check_fields(forward_fields, backward_fields)

classmethod determine_domain(*fields)

property discrete_wave_numbers

discretize(fft_interface, fft_interface_kwds, enable_opencl_host_buffer_mapping, **kwds)

property discretized

property forward_fields

property forward_transforms

get_mem_requests(**kwds)

indexed_wavenumbers(*wave_numbers)

initialize(fft_granularity=None, fft_concurrent_plans=1, fft_plan_workload=1, **kwds)

Should be called after all require_forward_transform and require_backward_transform calls.

Parameters:

• fft_granularity (int, optional) –

  Granularity of each directional fft plan.

  1: iterate over 1d lines (slices of dimension 1) 2: iterate over 2d planes (slices of dimension 2) 3: iterate over 3d blocks (slices of dimension 3) n-1: iterate over hyperplans (slices of dimension n-1) n : no iteration, the plan will handle the whole domain.

  Contiguous buffers with sufficient alignement are allocated. Default value is: 1 in 1D else n-1 (ie. hyperplans)

• fft_plan_workload (int, optional, defaults to 1) – The number of blocks of dimension fft_granularity that a single plan will handle at once. Default is one block.

• fft_concurrent_plans (int, optional, defaults to 1) – Number of concurrent plans. Should be 1 for HOST based FFT interfaces. Should be at least 3 for DEVICE based FFT interface if the device has two async copy engine (copy, transform, copy).

property initialized

property mem_tag

property name

property op

property output_parameters

push_expressions(*exprs)

property ready

require_backward_transform(field, axes=None, transform_tag=None, custom_input_buffer=None, matching_forward_transform=None, action=None, dump_energy=None, plot_energy=None, **kwds)

Same as require_forward_transform but for backward transforms. This corresponds to the following backward transform mappings:

if order[axis] is 0:

*no transform -> no transform

else, if order[axis] is even:

*C2C -> C2C *R2C -> C2R *DCT-I -> DCT-I *DCT-III -> DCT-II *DST-I -> DST-I *DST-III -> DST-II

else: (if order[axis] is odd)

*C2C -> C2C *R2C -> C2R *DCT-I -> DST-I *DCT-III -> DST-II *DST-I -> DCT-I *DST-III -> DCT-II

For backward transforms, boundary compatibility for output_fields is thus the following:

if axis is even:

Boundary should be exactly the same on the axis.

else, if axis is odd, boundary conditions change on this axe:

*(Periodic-Peridic) PER-PER -> PER-PER (Periodic-Periodic) *(Neumann-Neumann) EVEN-EVEN -> ODD-ODD (Dirichlet-Dirichlet) *(Neumann-Dirichlet) EVEN-ODD -> ODD-EVEN (Dirichlet-Neumann) *(Dirichlet-Neumann) ODD-EVEN -> EVEN-ODD (Neumman-Dirichlet) *(Dirichlet-Dirichlet) ODD-ODD -> EVEN-EVEN (Neumann-Neumann)

Order and boundary conditions are decuded from field.

Parameters:

• field (ScalarField) – The target field where the result of the inverse transform will be stored.

• axes (array-like of integers) – The axes to be transformed.

• transform_tag (str) – Extra tag to register the backward transform (a single scalar field can be transformed multiple times). Default tag is ‘default’.

• custom_input_buffer (None or str or F, optional) – Force this transform to take as input one of the two common transform group buffers. Default None value will force the user to supply an input buffer. Specifying ‘B0’ or ‘B1’ will tell the planner to take as transform input one of the two transform group buffers (that are used during all forward and backward transforms of the same transform group). This features allow FFT operators to save one buffer for the first backward transform. Specifying ‘auto’ will tell the planner to use the matching transform output buffer.

• action (BackwardTransfromAction, optional) – Defaults to SpectralTransformAction.OVERWRITE which will overwrite the compute slices of the given output field. SpectralTransformAction.ACCUMULATE will sum the current content of the field with the result of the backward transform.

• dump_energy (IOParams, optional, defaults to None) – Compute the energy for each wavenumber at given frequency before each transform. If None is passed, no files are generated (default behaviour).

• plot_energy (IOParams, optional, defaults to None) – Plot field energy before each call to the backward transform to a custom file. If None is passed, no plots are generated (default behaviour).

• compute_energy_frequencies (array like of integers, optional, defaults to None) – Extra frequencies where to compute energy.

Notes

IOParams filename is formatted before being used:

{fname} is replaced with discrete field name {ite} is replaced with simulation iteration id for plotting and ‘’ for file dumping.

dump_energy plot_energy result

None None nothing iop0 0 energy is computed and dumped every iop0.frequency iterations

0 iop1 energy is computed and dumped every iop1.frequency iterations

iop0 iop1 energy is computed every iop1.frequency and iop2.frequency iterations

dumped every iop0.frequency plotted every iop1.frequency

About frequency:

if (frequency<0) no dump if (frequency==0) dump at time of interests and last iteration if (frequency>=0) dump at time of interests, last iteration and every freq iterations

require_forward_transform(field, axes=None, transform_tag=None, custom_output_buffer=None, action=None, dump_energy=None, plot_energy=None, **kwds)

Tells this SpectralTransformGroup to build a forward SpectralTransform on given field. Only specified axes are transformed.

Boundary condition to FFT extension mapping:

Periodic: Periodic extension Homogeneous Dirichlet: Odd extension Homogeneous Neumann: Even extension

This leads to 5 possible transforms for each axis (periodic-periodic, even-even, odd-odd, even-odd, odd-even).

Forward transforms used for each axis per extension pair:

*Periodic-Periodic (PER-PER): DFT (C2C, R2C for the first periodic axis) *Dirichlet-Dirichlet (ODD-ODD): DST-I *Dirichlet-Neumann (ODD-EVEN): DST-III *Neumann-Dirichlet (EVEN-ODD): DCT-III *Neumann-Neumann (EVEN-EVEN): DCT-I

This method will return the SpectralTransform object associated to field.

Parameters:

• field (ScalarField) – The source field to be transformed.

• axes (array-like of integers) – The axes to be transformed.

• transform_tag (str) – Extra tag to register the forward transform (a single scalar field can be transformed multiple times). Default tag is ‘default’.

• custom_output_buffer (None or str, optional) – Force this transform to output in one of the two common transform group buffers. Default None value will force the user allocate an output buffer. Specifying ‘B0’ or ‘B1’ will tell the planner to output the transform in one of the two transform group buffers (that are used during all forward and backward transforms of the same transform group). This features allow FFT operators to save one buffer for the last forward transform. Specifying ‘auto’ will tell the planner to choose either ‘B0’ or ‘B1’.

• action (BackwardTransfromAction, optional) – Defaults to SpectralTransformAction.OVERWRITE which will overwrite the compute slices of the output buffer. SpectralTransformAction.ACCUMULATE will sum the current content of the buffer with the result of the forward transform.

• dump_energy (IOParams, optional, defaults to None) – Compute the energy for each wavenumber at given frequency after each transform. If None is passed, no files are generated (default behaviour).

• plot_energy (IOParams, optional, defaults to None) – Plot field energy after each call to the forward transform to a custom file. If None is passed, no plots are generated (default behaviour).

• compute_energy_frequencies (array like of integers, optional, defaults to None) – Extra frequencies where to compute energy.

Notes

IOParams filename is formatted before being used:

{fname} is replaced with discrete field name {ite} is replaced with simulation iteration id for plotting and ‘’ for file dumping.

dump_energy plot_energy result

None None nothing iop0 0 energy is computed and dumped every iop0.frequency iterations

0 iop1 energy is computed and dumped every iop1.frequency iterations

iop0 iop1 energy is computed every iop1.frequency and iop2.frequency iterations

dumped every iop0.frequency plotted every iop1.frequency

About frequency:

if (frequency<0) no dump if (frequency==0) dump at time of interests and last iteration if (frequency>=0) dump at time of interests, last iteration and every freq iterations

setup(work)

property tag